import { Meta } from '@storybook/addon-docs';

<Meta title="API Reference/Properties" id="api-props" />

# General Properties

| Property           | Type                 | Required | Default  | Description                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------ | -------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| columns            | array                | yes      | []       | DataTable [column definitions](/docs/api-columns--page#column-definitions-api)                                                                                                                                                                                                                                                                                                                                    |
| data               | array                | no       | []       | It's **highly recommended** that your data have a unique identifier (keyField). The default `keyField` is `id`. If you need to override this value then use the `keyField` proeprty below                                                                                                                                                                                                                         |
| keyField           | string               | no       | 'id'     | **Your data MUST HAVE a unique identifier**. By default, React Data Table looks for an `id` property on each item in your data. You must match `keyField` to that identifier key.<br /><br />If a unique `id` is not present, React Data Table will attempt to use the row index and by reference checks as fallbacks, however, certain features will not work correctly                                          |
| title              | string or component  | no       |          | The title displayed in the Table Header. If you do not provide the `title` property the Table Header will not be rendered
| ariaLabel          | string               | no       |          | Adds `aria-label` attribute to the table for accessibility purposes. If you do not provide the `ariaLabel` property aria-label will not be added at all
| responsive         | boolean              | no       | true     | Makes the table horizontally scrollable on smaller screen widths                                                                                                                                                                                                                                                                                                                                                  |
| striped            | boolean              | no       | false    | Stripe/band color the odd rows                                                                                                                                                                                                                                                                                                                                                                                    |
| highlightOnHover   | boolean              | no       | false    | If rows are to be highlighted on hover                                                                                                                                                                                                                                                                                                                                                                            |
| pointerOnHover     | boolean              | no       | false    | If rows show a point icon on hover                                                                                                                                                                                                                                                                                                                                                                                |
| dense              | boolean              | no       | false    | Compacts the row height. can be overridden via theming `rows.denseHeight`. <br /><br />**Note:** If any custom elements exceed the dense height then the row will only compact to the tallest element any of your cells                                                                                                                                                                                           |
| noTableHead        | boolean              | no       | false    | Hides the the sort columns and titles (TableHead).<br /> <br /><br />**Note:** This negates sorting                                                                                                                                                                                                                                                                                                               |
| persistTableHead   | boolean              | no       | false    | Show the table head (columns) even when `progressPending` is true. <br /><br />**Note:** The `noTableHead` will always hide the table head (columns) even when using `persistTableHead`                                                                                                                                                                                                                           |
| noDataComponent    | string or component  | no       | built-in | A custom component to display when there are no records to display                                                                                                                                                                                                                                                                                                                                                |
| disabled           | boolean              | no       | false    | Disables the Table section                                                                                                                                                                                                                                                                                                                                                                                        |
| direction          | string               | no       | auto     | Accepts: `ltr`, `rtl`, or `auto`. When set to `auto` (default), RDT will attempt to detect direction by checking the HTML and DIV tags. For cases where you need to force rtl, or ltr just set this option manually (i.e. SSR).<br /><br />If you are using Typescript or prefer enums you can `import { Direction } from 'react-data-table-component';` and use `Direction.AUTO, Direction.LTR, or Direction.RTL |
| onRowClicked       | `(row, event) => {}` | no       |          | Callback to access the row, event on row click.<br /> <br /><br />**Note:** If you are using custom cells (`column[].cell`), you will need to apply the `data-tag="allowRowEvents"` to the innermost element or on the elements you want to propagate the `onRowClicked` event to.                                                                                                                                |
| onRowDoubleClicked | `(row, event) => {}` | no       |          | Callback to access the row, event on row double click.<br /><br />**Note:** If you are using custom cells (`column[].cell`), you will need to apply the `data-tag="allowRowEvents"` to the innermost element or on the elements you want to propagate the `onRowDoubleClicked` event to.                                                                                                                          |
| onRowMouseEnter    | `(row, event) => {}` | no       |          | Callback to access the row, event on the mouse entering the row.                                                                                                                                                                                                                                                                                                                                                  |
| onRowMouseLeave    | `(row, event) => {}` | no       |          | Callback to access the row, event on the mouse leaving the row.                                                                                                                                                                                                                                                                                                                                                   |

# Columns

| Property            | Type                | Required | Default | Description                      |
| ------------------- | ------------------- | -------- | ------- | -------------------------------- |
| onColumnOrderChange | `(nextOrder) => {}` | no       |         | returns an array of TableColumns |

# Sorting

| Property           | Type              | Required | Default  | Description                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------ | ----------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| defaultSortFieldId | string or number  | no       | null     | The `defaultSortFieldId` sets the a column to be pre sorted and corresponds to the a column definition `id`                                                                                                                                                                                                                                                                                                               |
| defaultSortAsc     | boolean           | no       | true     | Set this to false if you want the table data to be sorted in DESC order.<br /><br />**Note:** This will apply work when the table is initially loaded                                                                                                                                                                                                                                                                     |
| sortIcon           | component         | no       | built-in | Override the default sort icon - the icon must be a font or svg icon and it should be a "downward" icon since animation will be handled by React Data Table                                                                                                                                                                                                                                                               |
| sortServer         | boolean           | no       | false    | Disables internal sorting for use with server-side/remote sorting or when you want to manually control the sort behavior. place your sorting logic and/or api calls in an `onSort` handler. <br /><br />**Note:** `sortFunction` is a better choice if you simply want to override the internal sorting behavior                                                                                                          |
| sortFunction       | _See description_ | no       | null     | Pass in your own custom sort function. **Your function must return an new array reference**, otherwise RDT will not re-render. For example, `Array.sort` sorts the array in place but because of JavaScript object equality it will be the same reference and will not re-render. A common pattern is to return `yourArray.slice(0)` which creates a new array. <br /><br />**Type:** `(rows, selector, direction) => {}` |
| onSort             | _See description_ | no       |          | Callback to access the sort state when a column is clicked. Returns `(column, sortDirection, event)`. See [Columns](/docs/api-columns--page) for Column Definitions API. <br /><br />**Type:** `(selectedColumn, sortDirection, sortedRows) => {}`                                                                                                                                                                        |

# Row Selection

| Property                     | Type              | Required | Default  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------------- | ----------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| selectableRows               | boolean           | no       | false    | Whether to show selectable checkboxes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| selectableRowsVisibleOnly    | boolean           | no       | false    | When using using `pagination` and `selectableRows` all rows in `data` are selected by default if you check the select all rows checkbox. For example, if you have 20 rows and with `pagination` 10 rows per page clicking on the select all checkbox results in 20 rows being selected (i.e. rows are selected that are not in the view). However, with `selectableRowsVisibleOnly` only the 10 rows that are visible (those that are on the current page) are allowed to be selected using select all. <br /><br />Things to note when using `selectableRowsVisibleOnly`: <br /> 1. When you sort then selected items will be cleared <br />2. When using `sortServer` for server side sorting you do not need to set `selectableRowsVisibleOnly` as the behavior is implicit |
| selectableRowsHighlight      | boolean           | no       | false    | Highlight a row when it is selected                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| selectableRowsSingle         | boolean           | no       | false    | Switches to single row selection mode. `onSelectedRowsChange` will still return an array of `selectedRows`, but it will only be a single array item                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| selectableRowsNoSelectAll    | boolean           | no       | false    | Whether to show the select all rows checkbox                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| clearSelectedRows            | boolean           | no       | false    | Toggling this property clears the selectedRows. If you use redux or react state you need to make sure that you pass a toggled value or the component will not update. See [Clearing Selected Rows](/docs/selectable-manage-selections--manage-selections#clearing-row-selections)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| selectableRowsComponent      | component         | no       | built-in | Overrides the default checkbox component. Must be passed as: `Checkbox` not `<Checkbox />`. You can also find UI Library Integration examples [here](/docs/getting-started-library-integration--page)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| selectableRowsComponentProps | object            | no       | {}       | Additional props you want to pass to `selectableRowsComponent`. See [Material UI Example](/docs/ui-library-material-ui-table--table) to learn how you can override indeterminate state                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| selectableRowSelected        | `(row) => {}`     | no       |          | Select a row based on a property in your data. e.g. `row => row.isSelected`. `selectableRowSelected` must return a boolean to determine if the row should be programatically selected. <br /><br />**Important Notes:**<br />- Changing the state of selectableRowSelected will NOT re-render RDT, instead you should change your data if you want to update the items that are selected.<br />- When using `selectableRowsSingle` `selectableRowSelected` will only return the first match                                                                                                                                                                                                                                                                                    |
| selectableRowDisabled        | `(row) => {}`     | no       |          | Disable row select based on a property in your data. e.g. `row => row.isDisabled`. `selectableRowDisabled` must return a boolean to determine if the row should be programatically disabled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| onSelectedRowsChange         | _See description_ | no       |          | Callback that fires anytime the rows selected state changes. Returns `({ allSelected, selectedCount, selectedRows })`. <br /><br />**Type:** `({ allSelected; selectedCount; selectedRows }) => {}` <br /><br />**Note:** It's highly recommended that you memoize the callback that you pass to `onSelectedRowsChange` if it updates the state of your parent component. This prevents `DataTable` from unnecessary re-renders every time your parent component is re-rendered.                                                                                                                                                                                                                                                                                               |

# Row Expander

| Property                           | Type              | Required | Default                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------- | ----------------- | -------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| expandableRows                     | boolean           | no       | false                  | Whether to make a row expandable, if true it requires an `expandableRowsComponent`. It is **highly recommended** your data set have a unique identifier defined as the `keyField` for row expansion to work properly.                                                                                                                                                                                                                                                     |
| expandableIcon                     | object            | no       | default expander icons | you may pass in your own custom icons using the `expandableIcon: { collapsed: <svg>...</svg>, expanded: <svg>...</svg> }`                                                                                                                                                                                                                                                                                                                                                 |
| expandableRowExpanded              | `(row) => {}`     | no       |                        | Expand a row based on a property in your data. e.g. `row => row.expandMe`. `expandableRowExpanded` must return a boolean to determine if the row should be programatically expanded.                                                                                                                                                                                                                                                                                      |
| expandableRowDisabled              | `(row) => {}`     | no       |                        | Disable a row expand based on a property in your data. e.g. `row => row.expandDisabled`. `expandableRowDisabled` must return a boolean to determine if the row should be programatically disabled.                                                                                                                                                                                                                                                                        |
| expandableRowsComponent            | component         | no       |                        | A custom component to display in the expanded row. Must be passed as: `MyExpander` not `<MyExpander />`. Your component will have access to the row `data`. For example: `const MyExpander = props => <div>{props.data.name}</div>`                                                                                                                                                                                                                                       |
| expandableRowsComponentProps       | object            | no       |                        | Additional props you want to pass to your custom `expandableRowsComponent`. By default `expandableRowsComponent` will have a `data` prop that you may access the row data with. New props added via `expandableRowsComponentProps` wil be composed                                                                                                                                                                                                                        |
| expandOnRowClicked                 | boolean           | no       |                        | The default behavior is to expand the row when the expander button is clicked. `expandOnRowClicked` allows expanding the row when an area within the row is clicked. Requires `expandableRows` be set to true. <br /><br />**Note:** that if you are using custom cells (`column[].cell`), you will need to apply the `data-tag="allowRowEvents"` to the innermost element or on the elements you want to propagate the `expandOnRowClicked` event to.                    |
| expandOnRowDoubleClicked           | boolean           | no       |                        | The default behavior is to expand the row when the expander button is clicked. `expandOnRowDoubleClicked` allows expanding the row when an area within the row is double clicked. Requires `expandableRows` be set to true. <br /><br />**Note:** that if you are using custom cells (`column[].cell`), you will need to apply the `data-tag="allowRowEvents"` to the innermost element or on the elements you want to propagate the `expandOnRowDoubleClicked` event to. |
| expandableRowsHideExpander         | boolean           | no       | false                  | Do not render the expander button. This is useful when using `expandOnRowClicked` or `expandOnRowDoubleClicked`                                                                                                                                                                                                                                                                                                                                                           |
| expandableInheritConditionalStyles | boolean           | no       | false                  | Whether to apply `conditionalRowStyles` to the expander row                                                                                                                                                                                                                                                                                                                                                                                                               |
| onRowExpandToggled                 | _See description_ | no       |                        | When a row is Expanded or Collapsed `onRowExpandToggled` will fire and return `(toggleState, row)`. <br /><br />**Type:** `(expanded, row) => {}`                                                                                                                                                                                                                                                                                                                         |

# Pagination

| Property                     | Type              | Required | Default                                                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pagination                   | boolean           | no       | false                                                                                                        | Enable pagination with defaults. by default the total record set will be sliced depending on the page, rows per page. if you wish to use server side pagination then use the `paginationServer` property                                                                                                                                                                                                                    |
| paginationServer             | boolean           | no       | false                                                                                                        | Changes the default pagination to work with server side pagination                                                                                                                                                                                                                                                                                                                                                          |
| paginationServerOptions      | object            | no       | _See description_                                                                                            | When using `selectableRows` is used to make selected rows persist on page change and on sort when using server side pagination. <br /><br />**Default value:** `{ persistSelectedOnPageChange: false, persistSelectedOnSort: false }` <br /><br />**Note:** when using `persistSelectedOnPageChange` that select all checkbox will not be visible (i.e. you cannot select rows there you have to retrieved from the server) |
| paginationDefaultPage        | number            | no       | 1                                                                                                            | The default page to use when the table initially loads                                                                                                                                                                                                                                                                                                                                                                      |
| paginationResetDefaultPage   | boolean           | no       | false                                                                                                        | The prop can be "toggled" to reset the pagination back to `paginationDefaultPage`. For this to work make sure you are using some sort of state and toggling the prop. e.g. `setResetPaginationToggle(!resetPaginationToggle)` or for a class component `setState(resetPaginationToggle: !resetPaginationToggle)`                                                                                                            |
| paginationTotalRows          | number            | no       | 0                                                                                                            | Allows you to provide the total row count for your table as represented by your API when performing server side pagination. if this property is not provided then react-data-table will use `data.length`                                                                                                                                                                                                                   |
| paginationPerPage            | number            | no       | 10                                                                                                           | The default rows per page to use when the table initially loads                                                                                                                                                                                                                                                                                                                                                             |
| paginationRowsPerPageOptions | number            | no       | `[10, 15, 20, 25, 30]`                                                                                       | Row page dropdown selection options                                                                                                                                                                                                                                                                                                                                                                                         |
| paginationComponent          | component         | no       | [Pagination](https://github.com/jbetancur/react-data-table-component/blob/next/src/DataTable/Pagination.tsx) | A component that overrides the default pagination component. It must satisfy the following API: `{ rowsPerPage: PropTypes.number.isRequired, rowCount: PropTypes.number.isRequired, onChangePage: PropTypes.func.isRequired, onChangeRowsPerPage: PropTypes.func.isRequired, currentPage: PropTypes.number.isRequired }`                                                                                                    |
| paginationComponentOptions   | object            | no       | _See description_                                                                                            | Override options for the built in pagination component. _Note that this prop only works with the built-in Pagination component._ <br /><br />**Default value:** `{ rowsPerPageText: 'Rows per page:', rangeSeparatorText: 'of', noRowsPerPage: false, selectAllRowsItem: false, selectAllRowsItemText: 'All' }`                                                                                                             |
| paginationIconFirstPage      | component         | no       | built-in                                                                                                     | A component that overrides the first page icon for the pagination. <br /><br />**Note:** that this prop only works with the build in Pagination component\*                                                                                                                                                                                                                                                                 |
| paginationIconLastPage       | component         | no       | built-in                                                                                                     | A component that overrides the last page icon for the pagination. <br /><br />**Note:** that this prop only works with the build in Pagination component\*                                                                                                                                                                                                                                                                  |
| paginationIconNext           | component         | no       | built-in                                                                                                     | A component that overrides the next page icon for the pagination. <br /><br />**Note:** that this prop only works with the build in Pagination component\*                                                                                                                                                                                                                                                                  |
| paginationIconPrevious       | component         | no       | built-in                                                                                                     | A component that overrides the previous page icon for the pagination. <br /><br />**Note:** that this prop only works with the build in Pagination component\*                                                                                                                                                                                                                                                              |
| onChangePage                 | _See description_ | no       | null                                                                                                         | Callback that fires when page is changed and returns `onChangePage (page, totalRows)`. <br /><br />**Type:** `(page, totalRows) => {}`                                                                                                                                                                                                                                                                                      |
| onChangeRowsPerPage          | _See description_ | no       | null                                                                                                         | Callback that fires when rows per page is changed and returns `onChangeRowsPerPage (currentRowsPerPage, currentPage)`. <br /><br />**Type:** `(currentRowsPerPage, currentPage) => {}`                                                                                                                                                                                                                                      |

# Headers

| Property                | Type      | Required | Default | Description                                                                                                                     |
| ----------------------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| actions                 | component | no       | null    | Add actions to the TableHeader                                                                                                  |
| noHeader                | boolean   | no       | false   | Removes the table header. `title`, `contextTitle` and `contextActions` will be ignored                                          |
| fixedHeader             | boolean   | no       | false   | Makes the table header fixed allowing you to scroll the table body                                                              |
| fixedHeaderScrollHeight | string    | no       | 100vh   | In order for fixedHeader to work this property allows you to set a static height to the TableBody. height must be a fixed value |
| subHeader               | boolean   | no       | false   | Show a sub header between the table and table header                                                                            |
| subHeaderAlign          | string    | no       | right   | Align the sub header content (left, right, center)                                                                              |
| subHeaderWrap           | boolean   | no       | true    | Whether the sub header content should wrap                                                                                      |
| subHeaderComponent      | component | no       | null    | A component you want to render                                                                                                  |

# Header Context Menu when using Selectable Rows

| Property         | Type      | Required | Default           | Description                                                                                                                                                                                                                                                                                                                                                        |
| ---------------- | --------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| contextMessage   | object    | no       | _See description_ | Override the context menu selected message when using `selectableRows`. <br /><br />**Default value:** `{ singular: 'item', plural: 'items', message: 'selected' }`                                                                                                                                                                                                |
| contextActions   | component | no       | null              | Add context actions to the context menu when using `selectableRows`                                                                                                                                                                                                                                                                                                |
| contextComponent | component | no       | null              | Overide the default context menu when using `selectableRows` with your own custom componet. RDT will compose the `selectedCount` prop to your custom component. For example, `const CustomContext = (selectedCount) => <div>{selectedCount}</div>` gives you access to the row count.<br /><br /> **Note:** This will negate `contextMessage` and `contextActions` |
| noContextMenu    | boolean   | no       | false             | Do not display the context menu when using `selectableRows`                                                                                                                                                                                                                                                                                                        |

# Progress/Loading Indicator

| Property          | Type      | Required | Default | Description                                                                                                                                                                  |
| ----------------- | --------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| progressPending   | boolean   | no       |         | Disables the table and displays a plain text Loading Indicator                                                                                                               |
| progressComponent | component | no       |         | Allows you to use your own custom progress component. Note that in some cases (e.g. animated/spinning circular indicators) you will need to add a wrapping div with padding. |

# Theming and Customization

| Property     | Type   | Required | Default | Description                                                                                                                                                                                         |
| ------------ | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| theme        | string | no       | default | Possible values are `default` or `dark`                                                                                                                                                             |
| customStyles | object | no       |         | [styles.js](https://github.com/jbetancur/react-data-table-component/blob/next/src/DataTable/styles.ts) for a detailed catalog of RDT styles that you can override or extend using css-in-js objects |
